Crate rug

source ·
Expand description

§Arbitrary-precision numbers

Rug provides integers and floating-point numbers with arbitrary precision and correct rounding:

  • Integer is a bignum integer with arbitrary precision,
  • Rational is a bignum rational number with arbitrary precision,
  • Float is a multi-precision floating-point number with correct rounding, and
  • Complex is a multi-precision complex number with correct rounding.

Rug is a high-level interface to the following GNU libraries:

  • GMP for integers and rational numbers,
  • MPFR for floating-point numbers, and
  • MPC for complex numbers.

Rug is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the full text of the GNU LGPL and GNU GPL for details.

You are also free to use the examples in this documentation without any restrictions; the examples are in the public domain.

§Quick example

use rug::{Assign, Integer};
let mut int = Integer::new();
assert_eq!(int, 0);
int.assign(14);
assert_eq!(int, 14);

let decimal = "98_765_432_109_876_543_210";
int.assign(Integer::parse(decimal).unwrap());
assert!(int > 100_000_000);

let hex_160 = "ffff0000ffff0000ffff0000ffff0000ffff0000";
int.assign(Integer::parse_radix(hex_160, 16).unwrap());
assert_eq!(int.significant_bits(), 160);
int = (int >> 128) - 1;
assert_eq!(int, 0xfffe_ffff_u32);
  • Integer::new creates a new Integer intialized to zero.
  • To assign values to Rug types, we use the Assign trait and its method Assign::assign. We do not use the assignment operator = as that would drop the left-hand-side operand and replace it with a right-hand-side operand of the same type, which is not what we want here.
  • Arbitrary precision numbers can hold numbers that are too large to fit in a primitive type. To assign such a number to the large types, we use strings rather than primitives; in the example this is done using Integer::parse and Integer::parse_radix.
  • We can compare Rug types to primitive types or to other Rug types using the normal comparison operators, for example int > 100_000_000.
  • Most arithmetic operations are supported with Rug types and primitive types on either side of the operator, for example int >> 128.

§Using with primitive types

With Rust primitive types, arithmetic operators usually operate on two values of the same type, for example 12i32 + 5i32. Unlike primitive types, conversion to and from Rug types can be expensive, so the arithmetic operators are overloaded to work on many combinations of Rug types and primitives. The following are provided:

  1. Where they make sense, all arithmetic operators are overloaded to work with Rug types and the primitives i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, f32 and f64.
  2. Where they make sense, conversions using the From trait and assignments using the Assign trait are supported for all the primitives in 1 above as well as bool, isize and usize.
  3. Comparisons between Rug types and all the numeric primitives listed in 1 and 2 above are supported.
  4. For Rational numbers, conversions and comparisons are also supported for tuples containing two integer primitives: the first is the numerator and the second is the denominator which must not be zero. The two primitives do not need to be of the same type.
  5. For Complex numbers, conversions and comparisons are also supported for tuples containing two primitives: the first is the real part and the second is the imaginary part. The two primitives do not need to be of the same type.

§Operators

Operators are overloaded to work on Rug types alone or on a combination of Rug types and Rust primitives. When at least one operand is an owned value of a Rug type, the operation will consume that value and return a value of the Rug type. For example

use rug::Integer;
let a = Integer::from(10);
let b = 5 - a;
assert_eq!(b, 5 - 10);

Here a is consumed by the subtraction, and b is an owned Integer.

If on the other hand there are no owned Rug types and there are references instead, the returned value is not the final value, but an incomplete-computation value. For example

use rug::Integer;
let (a, b) = (Integer::from(10), Integer::from(20));
let incomplete = &a - &b;
// This would fail to compile: assert_eq!(incomplete, -10);
let sub = Integer::from(incomplete);
assert_eq!(sub, -10);

Here a and b are not consumed, and incomplete is not the final value. It still needs to be converted or assigned into an Integer. This is covered in more detail in the Incomplete-computation values section.

§Shifting operations

The left shift << and right shift >> operators support shifting by negative values, for example a << 5 is equivalent to a >> -5.

The shifting operators are also supported for the Float and Complex number types, where they are equivalent to multiplication or division by a power of two. Only the exponent of the value is affected; the mantissa is unchanged.

§Exponentiation

Exponentiation (raising to a power) does not have a dedicated operator in Rust. In order to perform exponentiation of Rug types, the Pow trait has to be brought into scope, for example

use rug::ops::Pow;
use rug::Integer;
let base = Integer::from(10);
let power = base.pow(5);
assert_eq!(power, 100_000);

§Compound assignments to right-hand-side operands

Traits are provided for compound assignment to right-hand-side operands. This can be useful for non-commutative operations like subtraction. The names of the traits and their methods are similar to Rust compound assignment traits, with the suffix “Assign” replaced with “From”. For example the counterpart to SubAssign is SubFrom:

use rug::ops::SubFrom;
use rug::Integer;
let mut rhs = Integer::from(10);
// set rhs = 100 - rhs
rhs.sub_from(100);
assert_eq!(rhs, 90);

§Incomplete-computation values

There are two main reasons why operations like &a - &b do not perform a complete computation and return a Rug type:

  1. Sometimes we need to assign the result to an object that already exists. Since Rug types require memory allocations, this can help reduce the number of allocations. (While the allocations might not affect performance noticeably for computationally intensive functions, they can have a much more significant effect on faster functions like addition.)
  2. For the Float and Complex number types, we need to know the precision when we create a value, and the operation itself does not convey information about what precision is desired for the result.

There are two things that can be done with incomplete-computation values:

  1. Assign them to an existing object without unnecessary allocations. This is usually achieved using the Assign trait or a similar method, for example int.assign(incomplete) and float.assign_round(incomplete, Round::Up).
  2. Convert them to the final value using the Complete trait, the From trait or a similar method. For example incomplete integers can be completed using incomplete.complete() or Integer::from(incomplete). Incomplete floating-point numbers can be completed using incomplete.complete(53) or Float::with_val(53, incomplete) since the precision has to be specified.

Let us consider a couple of examples.

use rug::{Assign, Integer};
let mut buffer = Integer::new();
// ... buffer can be used and reused ...
let (a, b) = (Integer::from(10), Integer::from(20));
let incomplete = &a - &b;
buffer.assign(incomplete);
assert_eq!(buffer, -10);

Here the assignment from incomplete into buffer does not require an allocation unless the result does not fit in the current capacity of buffer. If &a - &b returned an Integer instead, then an allocation would take place even if it is not necessary.

use rug::float::Constant;
use rug::Float;
// x has a precision of 10 bits
let x = Float::with_val(10, 180);
// y has a precision of 50 bits
let y = Float::with_val(50, Constant::Pi);
let incomplete = &x / &y;
// z has a precision of 45 bits
let z = Float::with_val(45, incomplete);
assert!(57.295 < z && z < 57.296);

The precision to use for the result depends on the requirements of the algorithm being implemented. Here z is created with a precision of 45.

Many operations can return incomplete-computation values, for example

  • unary operators applied to references, for example -&int
  • binary operators applied to two references, for example &int1 + &int2
  • binary operators applied to a primitive and a reference, for example &int * 10
  • methods that take a reference, for example int.abs_ref()
  • methods that take two references, for example int1.gcd_ref(&int2)
  • string parsing, for example Integer::parse("12")

These operations return objects that can be stored in temporary variables like incomplete in the last few code examples. However, the names of the types are not public, and consequently, the incomplete-computation values cannot be for example stored in a struct. If you need to store the value in a struct, complete it to its final type and value.

§Using Rug

Rug is available on crates.io. To use Rug in your crate, add it as a dependency inside Cargo.toml:

[dependencies]
rug = "1.26"

Rug requires rustc version 1.65.0 or later.

Rug also depends on the GMP, MPFR and MPC libraries through the low-level FFI bindings in the gmp-mpfr-sys crate, which needs some setup to build; the gmp-mpfr-sys documentation has some details on usage under GNU/Linux, macOS and Windows.

§Optional features

The Rug crate has six optional features:

  1. integer, enabled by default. Required for the Integer type and its supporting features.
  2. rational, enabled by default. Required for the Rational number type and its supporting features. This feature requires the integer feature.
  3. float, enabled by default. Required for the Float type and its supporting features.
  4. complex, enabled by default. Required for the Complex number type and its supporting features. This feature requires the float feature.
  5. rand, enabled by default. Required for the RandState type and its supporting features. This feature requires the integer feature.
  6. std, enabled by default. This is for features that are not possible under no_std, such as methods that return String or the implementation of the Error trait.
  7. serde, disabled by default. This provides serialization support for the Integer, Rational, Float and Complex number types, providing that they are enabled. This feature requires the std feature and the serde crate.

The first six optional features are enabled by default; to use features selectively, you can add the dependency like this to Cargo.toml:

[dependencies.rug]
version = "1.26"
default-features = false
features = ["integer", "float", "std"]

Here only the integer, float and rand features are enabled. If none of the features are selected, the gmp-mpfr-sys crate is not required and thus not enabled. In that case, only the Assign trait and the traits that are in the ops module are provided by the crate.

§Experimental optional features

It is not considered a breaking change if the following experimental features are removed. The removal of experimental features would however require a minor version bump. Similarly, on a minor version bump, optional dependencies can be updated to an incompatible newer version.

  1. num-traits, disabled by default. This implements some traits from the num-traits crate and the num-integer crate. (The plan is to promote this to an optional feature once the num-traits crate and the num-integer crate reach version 1.0.0.)
  2. nightly-float, disabled by default. This requires the nightly compiler, and implements some operations with the experimental f16 and f128 primitives. (The plan is to always implement the operations and remove this experimental feature once the primitives are stabilized.)

Modules§

  • complex
    Multi-precision complex numbers with correct rounding.
  • float
    Multi-precision floating-point numbers with correct rounding.
  • integer
    Arbitrary-precision integers.
  • ops
    Operations on numbers.
  • rand
    Random number generation.
  • rational
    Arbitrary-precision rational numbers.

Structs§

  • Complex
    A multi-precision complex number with arbitrarily large precision and correct rounding.
  • Float
    A multi-precision floating-point number with arbitrarily large precision and correct rounding
  • Integer
    An arbitrary-precision integer.
  • Rational
    An arbitrary-precision rational number.

Traits§